JavaScripti Temporal API: kaasaegne kuupäevade ja kellaaegade haldamine globaalsele publikule

JavaScripti `Date` objekt on arendajatele juba ammu frustratsiooni valmistanud. Selle muudetavus, ebajärjekindel API ja kehv ajavööndite tugi on toonud kaasa hulgaliselt teeke, nagu Moment.js ja date-fns, et lünki täita. Nüüd pakub JavaScript Temporal API-ga kaasaegset sisseehitatud lahendust kuupäevade ja kellaaegade käsitlemiseks parema selguse ja täpsusega. See artikkel annab põhjaliku ülevaate Temporal API-st, keskendudes selle funktsioonidele, eelistele ja kasutamisele erinevates rahvusvahelistes kontekstides.

Mis on Temporal API?

Temporal API on uus globaalne objekt JavaScriptis, mis on loodud `Date` objekti puuduste kõrvaldamiseks. See pakub puhast, muutumatut API-d kuupäevade, kellaaegade, ajavööndite ja kalendrisüsteemidega töötamiseks. Oluline on, et see püüab esindada kuupäeva ja kellaaja mõisteid viisil, mis on tihedamalt seotud tegeliku kasutuse ja ootustega, muutes rahvusvahelistamise palju lihtsamaks.

Põhijooned:

• Muutumatus: Temporali objektid on muutumatud, mis tähendab, et toimingud, nagu päevade või kuude lisamine, tagastavad uued objektid, selle asemel et muuta algset. See välistab levinud vigade allika ja muudab koodi loogika jälgimise lihtsamaks.
• Selge API: Temporal pakub järjepidevat ja intuitiivset API-d tavaliste kuupäeva ja kellaaja toimingute jaoks.
• Ajavööndi tugi: Temporal sisaldab tugevat ajavööndite tuge, võimaldades teil töötada kuupäevade ja kellaaegadega erinevates asukohtades ilma vana `Date` objekti keerukusteta. See kasutab IANA ajavööndite andmebaasi, tagades täpse ja ajakohase teabe.
• Kalendrisüsteemid: Lisaks Gregoriuse kalendrile toetab Temporal ka alternatiivseid kalendrisüsteeme, rahuldades erinevate kultuuride ja piirkondade vajadusi.
• Parem täpsus: Temporal pakub nanosekundi täpsust, lahendades millisekundipõhise `Date` objekti piirangud.

Temporali põhilised objektid

Temporal API toob sisse mitu uut objektitüüpi. Siin on mõned peamised:

• `Temporal.PlainDate`: Esindab kuupäeva (aasta, kuu, päev) ilma ajavööndita.
• `Temporal.PlainTime`: Esindab kellaaega (tund, minut, sekund, millisekund, mikrosekund, nanosekund) ilma kuupäeva või ajavööndita.
• `Temporal.PlainDateTime`: Esindab kuupäeva ja kellaaega ilma ajavööndita.
• `Temporal.ZonedDateTime`: Esindab kuupäeva ja kellaaega kindla ajavööndiga.
• `Temporal.Instant`: Esindab kindlat ajahetke, mõõdetuna nanosekundites alates Unixi ajastu algusest (1. jaanuar 1970 UTC).
• `Temporal.TimeZone`: Esindab ajavööndit.
• `Temporal.Duration`: Esindab ajavahemikku (nt 2 tundi, 30 minutit).
• `Temporal.YearMonth`: Esindab aastat ja kuud.
• `Temporal.MonthDay`: Esindab kuud ja päeva.

Kuupäevadega töötamine

`Temporal.PlainDate` loomine

Et luua `Temporal.PlainDate`, võite kasutada konstruktorit:

            const plainDate = new Temporal.PlainDate(2024, 10, 27); // Aasta, Kuu (1-12), Päev
console.log(plainDate.toString()); // Väljund: 2024-10-27
            

              
                Copy
              
            
          

Saate kasutada ka meetodit `from`, mis aktsepteerib stringi ISO 8601 formaadis:

            const plainDateFromString = Temporal.PlainDate.from('2024-10-27');
console.log(plainDateFromString.toString()); // Väljund: 2024-10-27
            

              
                Copy
              
            
          

Kuupäeva komponentide saamine

Saate ligi pääseda üksikutele kuupäevakomponentidele, kasutades omadusi nagu `year`, `month` ja `day`:

            console.log(plainDate.year); // Väljund: 2024
console.log(plainDate.month); // Väljund: 10
console.log(plainDate.day); // Väljund: 27
            

              
                Copy
              
            
          

Kuupäeva aritmeetika

Päevade, nädalate, kuude või aastate liitmiseks või lahutamiseks kasutage meetodeid `plus` ja `minus`. Need meetodid tagastavad uue `Temporal.PlainDate` objekti:

            const nextWeek = plainDate.plus({ days: 7 });
console.log(nextWeek.toString()); // Väljund: 2024-11-03

const lastMonth = plainDate.minus({ months: 1 });
console.log(lastMonth.toString()); // Väljund: 2024-09-27
            

              
                Copy
              
            
          

Kuupäevade võrdlemine

Saate kuupäevi võrrelda meetodiga `compare`:

            const date1 = new Temporal.PlainDate(2024, 10, 27);
const date2 = new Temporal.PlainDate(2024, 11, 15);

console.log(Temporal.PlainDate.compare(date1, date2)); // Väljund: -1 (date1 on varasem kui date2)
            

              
                Copy
              
            
          

Kellaaegadega töötamine

`Temporal.PlainTime` loomine

Et luua `Temporal.PlainTime`, kasutage konstruktorit:

            const plainTime = new Temporal.PlainTime(10, 30, 0); // Tund, Minut, Sekund
console.log(plainTime.toString()); // Väljund: 10:30:00
            

              
                Copy
              
            
          

Või kasutage meetodit `from` koos ISO 8601 ajastringiga:

            const plainTimeFromString = Temporal.PlainTime.from('10:30:00');
console.log(plainTimeFromString.toString()); // Väljund: 10:30:00
            

              
                Copy
              
            
          

Kellaaja komponentide saamine

            console.log(plainTime.hour); // Väljund: 10
console.log(plainTime.minute); // Väljund: 30
console.log(plainTime.second); // Väljund: 0
            

              
                Copy
              
            
          

Kellaaja aritmeetika

            const later = plainTime.plus({ minutes: 15 });
console.log(later.toString()); // Väljund: 10:45:00
            

              
                Copy
              
            
          

Kuupäeva ja kellaajaga koos töötamine

`Temporal.PlainDateTime` loomine

Saate luua `Temporal.PlainDateTime` otse või kombineerides `Temporal.PlainDate` ja `Temporal.PlainTime`:

            const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
console.log(plainDateTime.toString()); // Väljund: 2024-10-27T10:30:00

const date = new Temporal.PlainDate(2024, 10, 27);
const time = new Temporal.PlainTime(10, 30, 0);
const combinedDateTime = date.toPlainDateTime(time);
console.log(combinedDateTime.toString()); // Väljund: 2024-10-27T10:30:00
            

              
                Copy
              
            
          

Ajavööndid

Ajavööndite korrektne käsitlemine on rakenduste jaoks, mis tegelevad eri asukohtades asuvate kasutajatega, ülioluline. Temporal API pakub tugevat ajavööndite tuge objektide `Temporal.ZonedDateTime` ja `Temporal.TimeZone` kaudu.

`Temporal.ZonedDateTime` loomine

Et luua `Temporal.ZonedDateTime`, vajate `Temporal.PlainDateTime` ja ajavööndi identifikaatorit. Ajavööndi identifikaatorid põhinevad IANA ajavööndite andmebaasil (nt `America/Los_Angeles`, `Europe/London`, `Asia/Tokyo`).

            const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
const timeZone = 'America/Los_Angeles';
const zonedDateTime = plainDateTime.toZonedDateTime(timeZone);
console.log(zonedDateTime.toString()); // Väljund: 2024-10-27T10:30:00-07:00[America/Los_Angeles] (Nihe sõltub suveaja reeglitest)

            

              
                Copy
              
            
          

Alternatiivina looge `Temporal.ZonedDateTime` objektist `Instant`.

            const instant = Temporal.Instant.fromEpochSeconds(1666866600); // Näite ajatempel
const zonedDateTimeFromInstant = instant.toZonedDateTimeISO(timeZone); // Ajavöönd nagu 'America/Los_Angeles'
console.log(zonedDateTimeFromInstant.toString());
            

              
                Copy
              
            
          

Ajavööndite vahel teisendamine

Saate teisendada `Temporal.ZonedDateTime` teise ajavööndisse, kasutades meetodit `withTimeZone`:

            const newTimeZone = 'Europe/London';
const zonedDateTimeInLondon = zonedDateTime.withTimeZone(newTimeZone);
console.log(zonedDateTimeInLondon.toString()); // Väljund: 2024-10-27T18:30:00+01:00[Europe/London]
            

              
                Copy
              
            
          

Ajavööndi nihetega töötamine

Objekti `Temporal.TimeZone` meetod `getOffsetStringFor` annab nihke stringi antud `Temporal.Instant` jaoks:

            const timeZoneObject = new Temporal.TimeZone(timeZone);
const offsetString = timeZoneObject.getOffsetStringFor(zonedDateTime.toInstant());
console.log(offsetString); // Väljund: -07:00 (Sõltuvalt suveaja reeglitest)
            

              
                Copy
              
            
          

Täpsete arvutuste tegemiseks on oluline kasutada korrektseid IANA ajavööndi identifikaatoreid. Neid identifikaatoreid hooldatakse ja uuendatakse regulaarselt, et kajastada suveaja ja ajavööndite piiride muutusi.

Ajavahemikud (Durations)

`Temporal.Duration` objekt esindab ajavahemikku. Seda saab kasutada kuupäevadele ja kellaaegadele lisamiseks või neist lahutamiseks.

`Temporal.Duration` loomine

Saate luua `Temporal.Duration`, kasutades konstruktorit ja määrates aastad, kuud, päevad, tunnid, minutid, sekundid, millisekundid, mikrosekundid ja nanosekundid:

            const duration = new Temporal.Duration(1, 2, 3, 4, 5, 6, 7, 8, 9); // Aastad, Kuud, Päevad, Tunnid, Minutid, Sekundid, Millisekundid, Mikrosekundid, Nanosekundid
console.log(duration.toString()); // Väljund: P1Y2M3DT4H5M6.007008009S
            

              
                Copy
              
            
          

Või kasutades ISO 8601 ajavahemiku stringi:

            const durationFromString = Temporal.Duration.from('P1Y2M3DT4H5M6S');
console.log(durationFromString.toString()); // Väljund: P1Y2M3DT4H5M6S
            

              
                Copy
              
            
          

Ajavahemike lisamine kuupäevadele ja kellaaegadele

            const plainDate = new Temporal.PlainDate(2024, 10, 27);
const duration = new Temporal.Duration(0, 0, 7); // 7 päeva
const newDate = plainDate.plus(duration);
console.log(newDate.toString()); // Väljund: 2024-11-03
            

              
                Copy
              
            
          

Pange tähele, et kuid või aastaid sisaldavate ajavahemike lisamine kuupäevadele nõuab hoolikat kaalumist, kuna päevade arv kuus või aastas võib varieeruda.

Kalendrisüsteemid

Temporal API toetab erinevaid kalendrisüsteeme peale Gregoriuse kalendri. See on ülioluline rakenduste jaoks, mis peavad käsitlema kuupäevi erinevates kultuurikontekstides. Kuigi tugi on veel arenemas, loob see aluse tulevaseks laienemiseks.

Alternatiivsete kalendrite kasutamine

Kindla kalendri kasutamiseks saate selle määrata Temporali objektide loomisel:

            const hebrewDate = new Temporal.PlainDate(5785, 1, 1, { calendar: 'hebrew' });
console.log(hebrewDate.toString()); // Konkreetne väljund võib varieeruda sõltuvalt implementatsioonist ja vormindamisest. Nõuab selle kirjutamise hetkel paljudes keskkondades polüfilli.
            

              
                Copy
              
            
          

Tähtis: Mitte-Gregoriuse kalendrite tugi võib nõuda polüfille või spetsiifilist brauseri/keskkonna tuge. Kontrollige uusimat teavet Temporal API dokumentatsioonist ja brauserite ühilduvustabelitest.

Kuupäevade ja kellaaegade vormindamine

Kuigi Temporal API keskendub kuupäeva ja kellaaja manipuleerimisele, tegeleb vormindamisega tavaliselt objekt `Intl.DateTimeFormat`, mis on osa Internationalization API-st. Temporali objektid töötavad sujuvalt koos objektiga `Intl.DateTimeFormat`.

`Intl.DateTimeFormat` kasutamine

Siin on, kuidas vormindada `Temporal.PlainDate` objekti `Intl.DateTimeFormat` abil:

            const plainDate = new Temporal.PlainDate(2024, 10, 27);
const formatter = new Intl.DateTimeFormat('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
console.log(formatter.format(plainDate)); // Väljund: October 27, 2024

const formatterGerman = new Intl.DateTimeFormat('de-DE', { year: 'numeric', month: 'long', day: 'numeric' });
console.log(formatterGerman.format(plainDate)); // Väljund: 27. Oktober 2024
            

              
                Copy
              
            
          

Saate vormindamisvalikuid oma vajadustele vastavaks kohandada. Esimene argument `Intl.DateTimeFormat` jaoks on lokaat, mis määrab vormindamisel kasutatava keele ja piirkondlikud tavad. Erinevate lokaatide (nt 'en-US', 'de-DE', 'fr-FR', 'ja-JP') kasutamine annab erinevaid väljundvorminguid.

`Temporal.ZonedDateTime` vormindamine

`Temporal.ZonedDateTime` vormindamine on sarnane, kuid saate väljundisse lisada ka ajavööndi teavet:

            const plainDateTime = new Temporal.PlainDateTime(2024, 10, 27, 10, 30, 0);
const timeZone = 'America/Los_Angeles';
const zonedDateTime = plainDateTime.toZonedDateTime(timeZone);

const formatter = new Intl.DateTimeFormat('en-US', { year: 'numeric', month: 'long', day: 'numeric', hour: 'numeric', minute: 'numeric', timeZoneName: 'short' });
console.log(formatter.format(zonedDateTime)); // Väljund: October 27, 2024, 10:30 AM PDT (Ajavööndi lühend sõltub suveaja reeglitest)
            

              
                Copy
              
            
          

Rahvusvahelistamise parimad praktikad

Globaalses kontekstis kuupäevade ja kellaaegadega töötamisel pidage meeles järgmisi parimaid praktikaid:

• Kasutage IANA ajavööndi identifikaatoreid: Kasutage alati IANA ajavööndi identifikaatoreid (nt `America/Los_Angeles`, `Europe/London`) täpseks ajavööndi käsitlemiseks.
• Olge teadlik suveajast: Suveaeg (DST) võib mõjutada ajavööndi nihkeid. Temporal API käsitleb suveaja üleminekuid automaatselt.
• Kasutage vormindamiseks `Intl.DateTimeFormat`: Kasutage kuupäevade ja kellaaegade vormindamiseks vastavalt kasutaja lokaadile objekti `Intl.DateTimeFormat`.
• Arvestage kalendrisüsteemidega: Kui teie rakendus peab toetama kasutajaid erinevates kultuurikontekstides, kaaluge alternatiivsete kalendrisüsteemide kasutamist.
• Salvestage kuupäevad ja kellaajad UTC-s: Kuupäevade ja kellaaegade andmebaasi salvestamisel on parim praktika salvestada need UTC-s (koordineeritud maailmaaeg), et vältida ajavööndi probleeme. Seejärel teisendage need kuvamiseks kohalikku aega. Temporal pakub meetodeid UTC-sse ja UTC-st teisendamiseks.
• Testige põhjalikult: Testige oma rakendust erinevate ajavööndite, lokaatide ja kalendrisüsteemidega, et tagada selle korrektne toimimine kõigi kasutajate jaoks.

Temporal API ja pärand `Date` objekti võrdlus

Siin on tabel, mis toob esile Temporal API peamised erinevused ja eelised võrreldes pärand `Date` objektiga:

Brauseritugi ja polüfillid

Kuna tegemist on suhteliselt uue API-ga, on brauserite tugi Temporal API-le veel arenemas. Kontrollige uusimaid brauserite ühilduvustabeleid (nt MDN Web Docs'ist), et näha, millised brauserid ja keskkonnad seda loomulikult toetavad. Vanemate brauserite või keskkondade jaoks, kus puudub loomulik tugi, saate kasutada polüfille, et pakkuda Temporal API funktsionaalsust. Otsige veebist "Temporal API polyfill", et leida sobivaid valikuid.

Kokkuvõte

JavaScripti Temporal API on oluline samm edasi kuupäevade ja kellaaegade käsitlemisel JavaScriptis. Selle muutumatus, selge API, tugev ajavööndite tugi ja kalendrisüsteemide võimekused muudavad selle võimsaks tööriistaks arendajatele, kes loovad rakendusi, mis peavad töötama kuupäevade ja kellaaegadega täpselt ja usaldusväärselt erinevates rahvusvahelistes kontekstides. Kuigi brauseritugi on veel arenemas, muudavad Temporal API eelised selle õppimist ja uutes projektides kasutuselevõttu väärt. Temporal API omaksvõtmise ja rahvusvahelistamise parimate praktikate järgimisega saate luua rakendusi, mis pakuvad sujuvat ja täpset kuupäeva- ja kellaajakogemust kasutajatele üle kogu maailma.

Lisalugemist

• Temporal API ametlik dokumentatsioon
• MDN Web Docs Temporalist